Java Client Server XML Web Services (JAX-WS) Tutorial

Table of content:

1. 1. Java API for XML Web Services (JAX-WS)
   2. Creating the web service
   3. Creating the server program
   4. Creating the client program

This tutorial walks you through the process of developing a client-server based application which involves in creating and using a web service in Java programming language. This article would be useful for those who are new with implementing web services in Java, as well as for the veteran who wants to revisit web services after a long holiday.

The application which we are going to build consists of two parts:

• • The server hosts a web service.
  • The client consumes the web service.

The web service receives an arbitrary string from client and returns a hashed String using MD5 digest algorithm. The server hosts and publishes the web service for serving requests from the client. Both server and client are console (command-line) programs.

To start, let’s take a brief look at a Java technology which is built for web services.

1. Understand Java API for XML Web Services (JAX-WS)

There are several technologies that make up the Java web services technology which is a part of Java EE platform, and JAX-WS is the main technology that integrates other ones like JAXB (Java Architecture for XML Binding) and SAAJ (SOAP with Attachments API for Java). In other words, when working with web services in Java, we work with JAX-WS directly, which is in turn, works with dependent technologies like JAXB and SAAJ.

For Java SE, JAX-WS has been included since Java SE 6. That means we can write web service-based console applications from Java SE 6, without downloading JAX-WS implementation package.

• • Home page: Java EE Web Services Technologies
  • Latest version: JAX-WS 2.2 (as of Nov 2012)
  • Download reference implementation: http://jax-ws.java.net
  • API documentation: http://jax-ws.java.net/nonav/jaxws-api/2.2/index.html

For the API, JAX-WS has two main packages:

• • javax.xml.ws: the core package of JAX-WS.
  • javax.jws: contains annotations to simplify writing code for web services, such as @WebService, @WebMethod, @WebParam…

In addition, Java SE comes with some command lines tools for simplifying generation of web services code: wgen, wsimport, schemagen and xjc. We will use the wsimport tool for generating some code for client part of the application.

2. Code the Java web service class

Now let’s create our web service class. The web service method returns a MD5-hahsed value of an input string. Using the annotations @WebService for the class and @WebMethod for the service method, create a class named MD5WebService.java as follows:

package net.codejava.webservices.server;

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService
public class MD5WebService {
	@WebMethod
	public String hashString(String input) {
		try {
			MessageDigest msgDigest = MessageDigest.getInstance("MD5");
			byte[] inputBytes = input.getBytes();
			byte[] hashedBytes = msgDigest.digest(inputBytes);

			StringBuffer sb = new StringBuffer();
			for (int i = 0; i < hashedBytes.length; i++) {
				sb.append(Integer.toString((hashedBytes[i] & 0xff) + 0x100, 16)
						.substring(1));
			}

			return sb.toString();
		} catch (NoSuchAlgorithmException ex) {
			ex.printStackTrace();
			return "";			
		}
	}
}

With help of the annotations, the web service class looks like just a normal Java class.

Type the following command to compile the web service class (suppose the current directory is parent of the directory structure for the package: net.codejava.webservices.server):

javac net\codejava\webservices\server\MD5WebService.java

3. Code the server program for Java web service

To create a simple, lightweight server for deploying the web service, we use the method publish() of the javax.xml.ws.Endpoint class:

publish(String address, Object implementor)

Where:

• • address: specifies an URI to which the web service is bound. The client will connect to the web service deployed on this server via this URI.
  • implementor: specifies an instance of the web service class.

Code the server class WebServiceServer.java, as follows:

package net.codejava.webservices.server;

import javax.xml.ws.Endpoint;

public class WebServiceServer {

	/**
	 * Starts a simple server to deploy the web service. 
	 */
	public static void main(String[] args) {
		String bindingURI = "http://localhost:9898/md5WebService";
		MD5WebService webService = new MD5WebService();
		Endpoint.publish(bindingURI, webService);
		System.out.println("Server started at: " + bindingURI);
	}
}

The JAX-WS implementation will create necessary infrastructure to start the server using some default configuration. And once started, the server is ready to receiving client’s requests.

Type the following command to compile the server class:

javac net\codejava\webservices\server\WebServiceServer.java

Start the server program using the following command:                                                               

java net.codejava.webservices.server.WebServiceServer

We should see the server started and is waiting for client’s requests at the command prompt:

Open a web browser and type the following URI into its address bar:

http://localhost:9898/md5WebService?wsdl

The browser will receive an XML document that describes the web service, as shown in the following screenshot:

4. Code the client program for Java web service

Before writing code for the client program, we have to generate some metadata code for the web service, by using the wsimporttool. This tool imports metadata about a web service provided by a URI and generates Java source files required for a web service client. Syntax of the wsimport command is as follows:

                         wsimport [options] <WSDL_URI>

Where:

• • options: specifies some options when generating the client code. You can type only wsimportin the command prompt to see a list of options.
  • WSDL_URI: specifies a URI that describes the web service.

Open another command prompt and change the current directory to the parent directory of net\codejava\webservices. Type the following command:

wsimport -keep -p net.codejava.webservices.client http://localhost:9898/md5WebService?wsdl

Note that the URI has the parameter wsdl, while the URI in the server class has not. The option -keep is to keep generated Java source files, and the option –p specifies the package name for the generated files.

Based on the information obtained from the web service, the wsimport tool generates the following classes (both .java and .class files) and put them under package net.codejava.webservices.client:

• • package-info.java
  • ObjectFactory.java
  • MD5WebServiceService.java
  • MD5WebService.java
  • HashStringResponse.java
  • HashString.java

We don’t have to modify these generated classes, most of time. Just use them! So code for the web service client class is fairly simple as follows:

package net.codejava.webservices.client;

public class WebServiceClient {

	/**
	 * Starts the web service client.
	 */
	public static void main(String[] args) {
		MD5WebServiceService client = new MD5WebServiceService();
		MD5WebService md5Webservice = client.getMD5WebServicePort();
		String hash = md5Webservice.hashString("admin");
		System.out.println("MD5 hash string: " + hash);
	}
}

This client program invokes the web service method hashString() and passes “admin” as an argument, and it will display the result received from web service server to the console. Type the following command to compile the web service client class:

javac net\codejava\webservices\client\WebServiceClient.java

And type this command to run the client program:

java net.codejava.webservices.client.WebServiceClient

The client connects to the server, invokes the remote method and receives the result, as shown in the following screenshot:

And that’s we have finished our journey on developing a fundamental client-server application for deploying and consuming a web service in Java.

NOTES: There is a small compatibility issue between JAX-WS 2.1 (Java SE 6) and JAX-WS 2.2 (Java SE 7), so the web service code compiled with Java SE 6 may not compile with Java SE 7, and vice versa.

You can also watch the video tutorial below:

Other Java Web Services Tutorial:

• Java RESTful Web Services Tutorial for Beginner with Jersey and Tomcat
• How to code and deploy Java XML Web Services (JAX-WS) on Tomcat
• Developing POJO web services using Apache Axis2, Ant and Tomcat
• Java Web Services Binary Data Transfer Example (base64 encoding)
• Monitoring SOAP Messages using TCP/IP Monitor in Eclipse
• Using MTOM to optimize binary data transfer with JAX-WS web services
• Java CRUD RESTful Web Services Examples with Jersey and Tomcat

About the Author:

Nam Ha Minh is certified Java programmer (SCJP and SCWCD). He began programming with Java back in the days of Java 1.4 and has been passionate about it ever since. You can connect with him on Facebook and watch his Java videos on YouTube.

Attachments:

WebServiceClientServerApp.zip

[Source code with compile instructions]

3 kB